home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK1.toast / Development Kits (Disc 1) / QuickDraw 3D / Development / 3DMF parser / 0.9 version / AREADME.TXT next >
Encoding:
Text File  |  1996-05-21  |  7.3 KB  |  184 lines  |  [TEXT/MPS ]
  1. QuickDraw 3D Metafile Read/Write API routines
  2.  
  3. ################################################################################
  4. # Compiler directives
  5. ################################################################################
  6.  
  7. When compiling on a Macintosh system, regardless of development environment,
  8. make sure you define the symbol __COMPILING_ON_MACINTOSH__
  9.  
  10. ################################################################################
  11. # What are the MF3D Routines?
  12. ################################################################################
  13.  
  14. The MF3D routines are a set of ANSI C source code files which allow developers
  15. who are not running QuickDraw 3D to read and to write QuickDraw 3D metafiles.
  16. The interface to the MF3D routines has been designed to be simple, however, it
  17. is assumed that anyone using these routines has a thorough understanding of
  18. the QuickDraw 3D metafile format. Such an understanding is especially important
  19. when writing files because these routines will not check, for example, that
  20. vertex attribute sets do not appear outside containers or that labels only
  21. appear on referenceable objects.
  22.  
  23. ################################################################################
  24. # Using the MF3D Routines
  25. ################################################################################
  26.  
  27. First, make sure that the types in "MF3DSysTypes.h" are defined as appropriate
  28. for your platform and system. If you alter the definition of the 64-bit integer
  29. types, then make sure that the macros in "MF3DInt64.h" are correct.
  30.  
  31. To read QuickDraw 3D metafiles:
  32. 1.    Call MF3DOpenInputStdCFile to open the file. MF3DOpenInputStdCFile requires
  33.     a standard C path name and returns an MF3D_FilePtr which you will use to
  34.     call the other MF3D routines. MF3DOpenInputStdCFile determines what kind of
  35.     file is being read, loads any tables of contents, and does some basic
  36.     sanity checks on the format.
  37. 2.    Call MF3DReadAnObject to read an object. The object will be returned as
  38.     type MF3DVoidObjPtr. You must then check object->objectType to find out
  39.     what type of object you have and cast the pointer as appropriate. All the
  40.     types and structures are defined in "MF3DObjects.h" and "MF3DSubObjects.h".
  41.     When you are finished with the object, call MF3DDisposeObject.
  42. 3.    Repeat Step 2 until kMF3DNoMoreObjects is returned.
  43. 4.    Call MF3DClose to clean up any internal data and to close the file.
  44.  
  45. To write QuickDraw 3D metafiles:
  46. 1.    Call MF3DOpenOutputStdCFile to open the file.
  47. 2.    Call MF3DWriteAnObject to write an object. The object you pass should be
  48.     one of the objects defined in "MF3DObjects.h" and "MF3DSubObjects.h".
  49. 3.    Repeat Step 2 until you have no more objects to write.
  50. 4.    Call MF3DClose to write the Table of Contents and to close the file.
  51.  
  52. ################################################################################
  53. # EndContainer object
  54. ################################################################################
  55.  
  56. Because the MF3D routines only work on an object at a time, an EndContainer
  57. object is used to mark the end of Container. The EndContainer object is not part
  58. of the QuickDraw 3D metafile specification, but should nevertheless be treated
  59. just like any other object when using the MF3D routines.
  60.  
  61. ################################################################################
  62. # Sample Code
  63. ################################################################################
  64.  
  65. main.c
  66.     Sample application that asks for a file (text or binary), reads objects
  67.     from that file, and writes them back out into a new text file.
  68. MPWMain.c
  69.     Sample MPW tool that accepts a parameter as the filename, reads objects
  70.     from that file, and writes them back out into a new binary file.
  71. MPWRefExample.c
  72.     Sample MPW tool that shows how to resolve internal and external references
  73.     which are read from a metafile.
  74. MPWTest.make
  75.     MPW Makefile that will build a tool using MPWMain.c
  76. MWPPC.ยต
  77.     Metrowerks C++ project that will build an application using main.c
  78.  
  79. ################################################################################
  80. # File Descriptions
  81. ################################################################################
  82.  
  83. #
  84. # External header files
  85. #    Anyone using the MF3D source code will be interested in these files
  86. #
  87. MF3D.h
  88.     External interface to the MF3D routines. Most applications should not need
  89.     to access any other routines.
  90. MF3DErrors.h
  91.     Various error codes returned by the MF3D routines.
  92. MF3DInt64.h
  93.     Macros needed to support usage of 64-bit integers. These need to be
  94.     updated if the definition of MF3DInt64 is changed in "MF3DTypes.h".
  95. MF3DObjects.h
  96.     Structural definition of the main (top-level) QuickDraw 3D Metafile
  97.     objects that can be returned.
  98. MF3DSubObjects.h
  99.     Structural definition of the other QuickDraw 3D Metafile objects that
  100.     can be returned. These objects are generally found inside a container.
  101. MF3DSysTypes.h
  102.     Basic system-dependent typedefs. These must be defined as appropriate
  103.     to the platform being used.
  104. MF3DTypes.h
  105.     Basic MF3D types.
  106.  
  107. #
  108. # External implementation file
  109. #
  110. MF3D.c
  111.     Implementation of MF3D external interface.
  112.  
  113. #
  114. # I/O routines
  115. #    Most developers will be able to use MF3DOpenInputStdCFile and
  116. #    MF3DOpenOutputStdCFile. Those who want to define their own I/O routines
  117. #    can use "MF3DStdCHooks.c" as an example.
  118. #
  119. MF3DIOCallback.h
  120.     Structure needed when calling MF3DOpenInput or MF3DOpenOutput directly.
  121. MF3DStdCHooks.c
  122. MF3DStdCHooks.h
  123.     Implementation to support MF3DOpenInputStdCFile and MF3DOpenOutputStdCFile.
  124.  
  125. #
  126. # Internal files
  127. #    These files will only be of interest to those who have a desire to
  128. #    modify the inner workings of the MF3D routines. Each internal file contains
  129. #    an underscore in its name. Also, the routines and types defined in these
  130. #    files also have underscores in their names.
  131. #
  132. MF3D_Assert.h
  133.     Set DEBUG to 1 if asserts are desired.
  134. MF3D_BinaryRead.c
  135. MF3D_BinaryRead.h
  136.     Miscellaneous functions to handle reading binary files.
  137. MF3D_File.c
  138. MF3D_File.h
  139.     Miscellaneous functions that mostly handle cleanup during close.
  140. MF3D_Groups.c
  141. MF3D_Groups.h
  142.     Functions that are available that could keep track of data when pushing
  143.     and popping groups. In Release 1.0 of MF3D, these functions essentially
  144.     do nothing.
  145. MF3D_IntObjects.h
  146.     Internal structures, including the MF3D_FilePtr.
  147. MF3D_Labels.c
  148. MF3D_Labels.h
  149.     Enum and Flags tables and lookup routines.
  150. MF3D_Macros.h
  151.     A couple of common macros.
  152. MF3D_Memory.c
  153. MF3D_Memory.h
  154.     Memory allocation routines. These could be replaced by those who
  155.     want to call platform-specific routines instead of the standard C library
  156.     routines.
  157. MF3D_Objects.c
  158. MF3D_Objects.h
  159.     All the functions which handle reading, writing, and disposing of the
  160.     various QuickDraw 3D Metafile objects.
  161. MF3D_ObjectType.c
  162.     Functions to convert between ASCII names and Binary types.
  163. MF3D_ObjectType.h
  164.     Tables linking ASCII names, Binary types, and read/write/dispose functions
  165.     of the various QuickDraw 3D Metafile objects.
  166. MF3D_Primitives.c
  167. MF3D_Primitives.h
  168.     Lower-level functions that handle reading and writing of basic types
  169.     (Text/Binary-independent).
  170. MF3D_Resolution.c
  171. MF3D_Resolution.h
  172.     Functions that keep track of things when resolving references.
  173. MF3D_TextRead.c
  174. MF3D_TextRead.h
  175.     Miscellaneous functions to handle reading text files.
  176. MF3D_TextStrings.h
  177.     Equates for various QuickDraw 3D Metafile characters.
  178. MF3D_TextUtils.c
  179. MF3D_TextUtils.h
  180.     Miscellaneous string utility functions.
  181. MF3D_TextWrite.c
  182. MF3D_TextWrite.h
  183.     Miscellaneous functions to handle writing text files.
  184.